fix these docs to reflect the current state of affairs

2001-02-20  Havoc Pennington  <hp@pobox.com>

	* gdk/tmpl/rgb.sgml: fix these docs to reflect the current state
	of affairs

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index a094c3ab411d767c344d39cf720edab448bb80c6..82615e1dedf2837816e6711fe919ed778cede2c1 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2001-02-20  Havoc Pennington  <hp@pobox.com>
+
+       * gdk/tmpl/rgb.sgml: fix these docs to reflect the current state
+       of affairs
+
 2001-02-19  Havoc Pennington  <hp@pobox.com>
 
        * gdk/Makefile.am (SCAN_OPTIONS): add --deprecated-guards

diff --git a/docs/reference/gdk/tmpl/rgb.sgml b/docs/reference/gdk/tmpl/rgb.sgml
index c60cde24acada129c18484716dcba7b2d618261d..a62e96e8428aee5a30797cb043204a3e42945816 100644 (file)
--- a/docs/reference/gdk/tmpl/rgb.sgml
+++ b/docs/reference/gdk/tmpl/rgb.sgml
@@ -2,59 +2,23 @@
 GdkRGB
 
 <!-- ##### SECTION Short_Description ##### -->
-displays RGB images (as well as grayscale and colormapped) to
-the native window.
+renders RGB, grayscale, or indexed image data to a #GdkDrawable
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
-
-GdkRgb converts RGB, grayscale, and colormapped images into the native
-window pixel format and displays them. It takes care of colormaps,
-visuals, dithering, and management of the temporary buffers.
-
-</para>
 
 <para>
-You must call gdk_rgb_init() before using any GdkRgb functionality. If
-you fail to do so, expect coredumps. All Gtk+ widgets that use GdkRgb
-(including #GtkPreview) call gdk_rgb_init() in their class_init method.
-Thus, if you use GdkRgb only indirectly, you don't need to worry
-about it.
+GdkRgb is a low-level module which renders RGB, grayscale, and indexed
+colormap images to a #GdkDrawable. It does this as efficiently as
+possible, handling issues such as colormaps, visuals, dithering,
+temporary buffers, and so on. Most code should use the higher-level
+#GdkPixbuf features in place of this module; for example,
+gdk_pixbuf_render_to_drawable() uses GdkRGB in its implementation.
 </para>
 
 <para>
-GdkRgb tries to use the system default visual and colormap, but
-doesn't always succeed. Thus, you have to be prepared to install the
-visual and colormap generated by GdkRgb. The following code sequence
-(before any widgets are created) should work in most applications:
-</para>
-
-<informalexample>
-<programlisting>
-  gdk_rgb_init ();
-
-  gtk_widget_set_default_colormap (gdk_rgb_get_cmap ());
-  gtk_widget_set_default_visual (gdk_rgb_get_visual ());
-</programlisting>
-</informalexample>
-
-<para>
-You can also push the colormap and visual, but in general it doesn't
-work unless the push wraps the window creation call. If you wrap the
-push around a widget which is embedded in a window without the GdkRgb
-colormap and visual, it probably won't work, and is likely to cause
-colormap flashing, as well.
-</para>
-
-<para>
-On 8-bit systems, the colormaps used by Imlib and GdkRgb may
-conflict. There is no good general solution to this other than phasing
-out the dependence on Imlib.
-</para>
-
-<para>
-You can set the threshold for installing colormaps with
-gdk_rgb_set_min_colors (). The default is 5x5x5 (125). If a colorcube
+GdkRGB allocates a color cube to use when rendering images.  You can
+set the threshold for installing colormaps with
+gdk_rgb_set_min_colors(). The default is 5x5x5 (125). If a colorcube
 of this size or larger can be allocated in the default colormap, then
 that's done. Otherwise, GdkRgb creates its own private colormap.
 Setting it to 0 means that it always tries to use the default
@@ -91,10 +55,10 @@ main (int argc, char *argv[])
   guchar *pos;
 
   gtk_init (&amp;argc, &amp;argv);
-  gdk_rgb_init ();
+
   window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
   darea = gtk_drawing_area_new ();
-  gtk_drawing_area_size (GTK_DRAWING_AREA (darea), IMAGE_WIDTH, IMAGE_HEIGHT);
+  gtk_widget_set_usize (darea, IMAGE_WIDTH, IMAGE_HEIGHT);
   gtk_container_add (GTK_CONTAINER (window), darea);
   gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
                       GTK_SIGNAL_FUNC (on_darea_expose), NULL);
@@ -139,32 +103,26 @@ on_darea_expose (GtkWidget *widget,
 colors.</para></listitem>
 </varlistentry>
 
+<varlistentry>
+<term>#GdkPixbuf and gdk_pixbuf_render_to_drawable()</term>
+<listitem><para>Higher-level image handling.</para></listitem>
+</varlistentry>
+
 </variablelist>
 
 </para>
 
 <!-- ##### FUNCTION gdk_rgb_init ##### -->
 <para>
-Initializes GdkRgb statically. It may be called more than once with no
-ill effects. It must, however, be called before any other GdkRgb
-operations are performed.
-</para>
-
-<para>
-The GdkRgb "context" is allocated statically. Thus, GdkRgb may be used
-to drive only one visual in any given application. GdkRgb
-automatically selects a best visual and sets its own colormap, if
-necessary. gdk_rgb_get_visual() and gdk_rgb_get_cmap () retrieve
-the chosen visual and colormap, respectively.
+This function no longer does anything at all. It's completely useless
+(and harmless).
 </para>
 
 
-
 <!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
 <para>
 Draws an RGB image in the drawable. This is the core GdkRgb
-function, and likely the only one you will need to use other than the
-initialization stuff.
+function, and likely the only one you will need to use.
 </para>
 
 <para>
@@ -448,8 +406,11 @@ private colormap.
 
 <!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
 <para>
-Gets the visual chosen by GdkRgb. This visual and the corresponding
-colormap should be used when creating windows that will be drawn in by GdkRgb.
+Gets a "preferred visual" chosen by GdkRgb. In previous versions of
+GDK, this was the only visual GdkRgb could use for rendering. In
+current versions, it's simply the visual GdkRgb would have chosen as 
+the optimal one in those previous versions. GdkRgb can now render to 
+drawables with any visual.
 </para>
 
 @Returns: The #GdkVisual chosen by GdkRgb.